---
type: integration
title: '@astrojs/preact'
description: '@astrojs/preact 프레임워크 통합을 사용하여 Astro 프로젝트에서 컴포넌트 지원을 확장하는 방법을 알아보세요.'
githubIntegrationURL: 'https://github.com/withastro/astro/tree/main/packages/integrations/preact/'
category: renderer
i18nReady: true
---

import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'

이 **[Astro 통합][astro-integration]** 을 통해 [Preact](https://preactjs.com/) 컴포넌트에 대한 서버 측 렌더링 및 클라이언트 측 하이드레이션이 가능해졌습니다.

## 왜 Preact인가?

Preact는 웹용 대화형 UI 컴포넌트를 빌드할 수 있는 라이브러리입니다. JavaScript를 사용하여 사이트에 대화형 기능을 빌드하려면 브라우저 API를 직접 사용하는 대신 컴포넌트 형식을 사용하는 것이 좋습니다.

이전에 React를 사용해 본 적이 있다면 Preact도 좋은 선택입니다. Preact는 React와 동일한 API를 제공하지만 훨씬 더 작은 3kB 패키지로 제공됩니다. `compat` 구성 옵션을 사용하여 많은 React 컴포넌트 렌더링도 지원합니다 (아래 참조).

**이 통합을 사용하기 전에 Preact에 대해 자세히 알아보고 싶으신가요?**\
웹사이트에서 대화형 튜토리얼인 [“10분 안에 Preact 배우기”](https://preactjs.com/tutorial)를 확인하세요.

## 설치

Astro에는 공식 통합 설정을 자동화하는 `astro add` 명령이 포함되어 있습니다. 원하는 경우 대신 [통합을 수동으로 설치](#수동-설치)할 수 있습니다.

`@astrojs/preact`를 설치하려면 프로젝트 디렉터리에서 다음을 실행하고 프롬프트를 따르세요.

<PackageManagerTabs>
  <Fragment slot="npm">
  ```sh
  npx astro add preact
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```sh
  pnpm astro add preact
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```sh
  yarn astro add preact
  ```
  </Fragment>
</PackageManagerTabs>

문제가 발생하면 [GitHub에서 언제든지 보고](https://github.com/withastro/astro/issues)하고 아래 수동 설치 단계를 시도해 보세요.

### 수동 설치

먼저 `@astrojs/preact` 패키지를 설치하세요.

<PackageManagerTabs>
  <Fragment slot="npm">
  ```sh
  npm install @astrojs/preact
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```sh
  pnpm add @astrojs/preact
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```sh
  yarn add @astrojs/preact
  ```
  </Fragment>
</PackageManagerTabs>

대부분의 패키지 관리자는 관련 피어 종속성도 설치합니다. Astro를 시작할 때 "Cannot find package 'preact'" (또는 이와 유사한) 경고가 표시되면 Preact를 설치해야 합니다.

<PackageManagerTabs>
  <Fragment slot="npm">
  ```sh
  npm install preact
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```sh
  pnpm add preact
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```sh
  yarn add preact
  ```
  </Fragment>
</PackageManagerTabs>

그런 다음 `integrations` 속성을 사용하여 `astro.config.*` 파일에 통합을 적용합니다.

```js title="astro.config.mjs" ins={2} ins="preact()"
import { defineConfig } from 'astro/config';
import preact from '@astrojs/preact';

export default defineConfig({
  // ...
  integrations: [preact()],
});
```

## 사용하기

Astro에서 첫 번째 Preact 컴포넌트를 사용하려면 [UI 프레임워크 문서][astro-ui-frameworks]로 이동하세요. 다음을 탐색하게 됩니다.

* 📦 프레임워크 컴포넌트가 로드되는 방식,
* 💧 클라이언트 측 하이드레이션 옵션 
* 🤝 프레임워크를 함께 혼합하고 중첩할 수 있는 기회

또한 통합에 대한 자세한 내용은 [Astro 통합 문서][astro-integration]를 확인하세요.

## 구성

Astro Preact 통합은 Preact 컴포넌트가 렌더링되는 방식을 처리하며 자체 옵션이 있습니다. 프로젝트의 통합 설정이 있는 `astro.config.mjs` 파일에서 이를 변경하세요.

기본 사용의 경우 Preact 통합을 구성할 필요가 없습니다.

### compat

React의 대규모 라이브러리를 사용자의 웹 브라우저에 설치하거나 제공할 필요 없이 React 컴포넌트를 렌더링하기 위한 Preact의 호환성 레이어인 `preact/compat`를 활성화할 수 있습니다.

이렇게 하려면 객체를 Preact 통합에 전달하고 `compat: true`를 설정하세요.

```js title="astro.config.mjs" "compat: true"
import { defineConfig } from 'astro/config';
import preact from '@astrojs/preact';

export default defineConfig({
  integrations: [preact({ compat: true })],
});
```

`compat` 옵션이 활성화되면 Preact 통합은 React 컴포넌트와 Preact 컴포넌트를 프로젝트에 렌더링하고 Preact 컴포넌트 내에서 React 컴포넌트를 가져올 수도 있습니다. Preact 웹사이트의 ["React에서 Preact로 전환"](https://preactjs.com/guide/v10/switching-to-preact)에서 자세한 내용을 읽어보세요.

React 컴포넌트 라이브러리를 가져올 때 `react` 및 `react-dom` 종속성을 `preact/compat`으로 교체하려면 [`overrides`](https://docs.npmjs.com/cli/v8/configuring-npm/package-json#overrides)를 사용하면 됩니다.

```json title="package.json"
{
  "overrides": {
    "react": "npm:@preact/compat@latest",
    "react-dom": "npm:@preact/compat@latest"
  }
}
```

해당 overrides 기능에 대해서는[`pnpm` overrides](https://pnpm.io/package_json#pnpmoverrides) 및 [`yarn` resolutions](https://yarnpkg.com/configuration/manifest#resolutions) 문서를 확인하세요.

:::note
현재 `compat` 옵션은 코드를 ESM으로 내보내는 React 라이브러리에서만 작동합니다. 빌드 시 오류가 발생하면 `astro.config.mjs` 파일의 `vite.ssr.noExternal: ['the-react-library']`에 라이브러리를 추가해 보세요.
:::

## 옵션

### 여러 JSX 프레임워크 결합

동일한 프로젝트에서 여러 JSX 프레임워크 (React, Preact, Solid)를 사용하는 경우 Astro는 각 컴포넌트에 어떤 JSX 프레임워크별 변환을 사용해야 하는지 결정해야 합니다. 프로젝트에 하나의 JSX 프레임워크 통합만 추가한 경우 추가 구성이 필요하지 않습니다.

어떤 파일이 어떤 프레임워크에 속하는지 지정하려면 `include` (필수) 및 `exclude` (선택 사항) 구성 옵션을 사용하세요. 사용 중인 각 프레임워크에 `포함`할 파일 및/또는 폴더 배열을 제공하세요. 와일드카드를 사용하여 여러 파일 경로를 포함할 수 있습니다.

포함을 더 쉽게 지정할 수 있도록 공통 프레임워크 컴포넌트를 동일한 폴더 (예: `/components/react/` 및 `/components/solid/`)에 배치하는 것이 좋지만 필수는 아닙니다.

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import preact from '@astrojs/preact';
import react from '@astrojs/react';
import svelte from '@astrojs/svelte';
import vue from '@astrojs/vue';
import solid from '@astrojs/solid-js';

export default defineConfig({
  // 다양한 종류의 컴포넌트를 지원하기 위해 많은 프레임워크를 활성화합니다.
  // 단일 JSX 프레임워크만 사용하는 경우 `include`가 필요하지 않습니다!
  integrations: [
    preact({
      include: ['**/preact/*'],
    }),
    react({
      include: ['**/react/*'],
    }),
    solid({
      include: ['**/solid/*'],
    }),
  ],
});
```

## 예시

* [Astro Preact 예시](https://github.com/withastro/astro/tree/latest/examples/framework-preact)는 Astro 프로젝트에서 대화형 Preact 컴포넌트를 사용하는 방법을 보여줍니다.
* [Astro Nanostores 예시](https://github.com/withastro/astro/tree/latest/examples/with-nanostores)는 서로 다른 컴포넌트, 심지어는 서로 다른 프레임워크 간 상태를 공유하는 방법을 보여줍니다! — Astro 프로젝트에서


[astro-integration]: /ko/guides/integrations-guide/

[astro-ui-frameworks]: /ko/guides/framework-components/#프레임워크-컴포넌트-사용하기
